What It Is
container machine gives you a persistent Linux environment on your Mac. Unlike an app-style container, a container machine is meant to feel like a lightweight Linux workstation with your macOS home directory mapped in.
bash
1# Your macOS home directory is available inside the machine2container machine run -n dev pwdInstallation & Setup
Start the Apple Container Service First
bash
1container system start2container system statusUseful Aliases
bash
1alias cm='container machine'2alias cmls='container machine ls'3alias cmrun='container machine run'Quickstart
bash
1container machine create alpine:latest --name dev2container machine run -n dev whoami3container machine run -n dev pwd4container machine run -n devMachine Lifecycle
Create Machines
bash
1container machine create alpine:latest --name dev2container machine create ubuntu:latest --name ubuntu-dev --cpus 4 --memory 8G3container machine create --set-default alpine:latest --name default-dev4container machine create --no-boot alpine:latest --name cold-dev5container machine create --home-mount ro alpine:latest --name safe-devOpen a Shell or Run One Command
bash
1container machine run -n dev2container machine run -n dev uname -a3container machine run -n dev -- cat /etc/os-release4container machine run -n dev --root whoami5container machine run -n dev -e APP_ENV=dev -- sh -lc 'env | grep APP_ENV'List, Inspect, Stop, Delete
bash
1container machine ls2container machine ls --format json3container machine inspect dev4container machine stop dev5container machine rm devDefault Machine
bash
1container machine set-default dev2container machine run3container machine inspect4container machine stopConfiguration & Resources
Change CPUs, Memory, Home Mount
bash
1container machine set -n dev cpus=4 memory=8G2container machine set -n dev home-mount=ro3container machine set -n dev home-mount=none4
5# Changes apply after restart6container machine stop dev7container machine run -n dev -- nprocCustom Kernel & Nested Virtualization
bash
1# Requires Apple Silicon M3+, macOS 15+, and a kernel with CONFIG_KVM=y2container machine create \3 --virtualization \4 --kernel /path/to/vmlinux-kvm \5 --name kvm-dev \6 alpine:latest7
8container machine set -n dev virtualization=true kernel=/path/to/vmlinux-kvm9container machine stop dev10container machine run -n dev -- ls -l /dev/kvm11
12# Reset to the default kernel13container machine set -n dev kernel=Logs & Troubleshooting
Machine Logs
bash
1container machine logs dev2container machine logs -f dev3container machine logs -n 200 dev4container machine logs --boot devSystem-Level Checks
bash
1container system status2container system version3container system logs --last 30mCommon Workflows
Daily Linux Dev Environment
bash
1container machine create ubuntu:latest --name work --set-default2container machine run3cd ~/Code/my-projectRun Package or Build Commands
bash
1container machine run -n work -- apt update2container machine run -n work -- apt install -y build-essential git3container machine run -n work -- make testWork as Root When Needed
bash
1container machine run -n work --root apt update2container machine run -n work --root idTest Across Distros
bash
1container machine create alpine:latest --name alpine-dev2container machine create ubuntu:latest --name ubuntu-dev3container machine run -n alpine-dev -- cat /etc/os-release4container machine run -n ubuntu-dev -- cat /etc/os-releaseBuild a Custom Machine Image
Minimal Ubuntu Machine Image
dockerfile
1FROM ubuntu:24.042
3ENV container container4
5RUN apt-get update && \6 apt-get install -y \7 dbus systemd openssh-server net-tools iproute2 iputils-ping curl wget vim-tiny man sudo && \8 apt-get clean && \9 rm -rf /var/lib/apt/lists/* && \10 yes | unminimize11
12RUN >/etc/machine-id13RUN >/var/lib/dbus/machine-id14
15RUN systemctl set-default multi-user.targetBuild and Create a Machine from It
bash
1container build -t local/ubuntu-machine:latest .2container machine create local/ubuntu-machine:latest --name ubuntu-machine3container machine run -n ubuntu-machineCustom First-Boot User Setup
bash
1# Add an executable script to the image at:2/etc/machine/create-user.shtext
1Available environment variables on first boot:2CONTAINER_GID3CONTAINER_HOME4CONTAINER_MACHINE_ID5CONTAINER_UID6CONTAINER_USER